Skip to main content
GET
/
api
/
v1
/
gateways
List Gateways
curl --request GET \
  --url https://api.example.com/api/v1/gateways
{
  "items": [
    {
      "id": "<string>",
      "organization_id": "<string>",
      "name": "<string>",
      "url": "<string>",
      "token": "<string>",
      "workspace_root": "<string>",
      "gateway_agent_id": "<string>",
      "allow_insecure_tls": true,
      "disable_device_pairing": true,
      "created_at": {},
      "updated_at": {}
    }
  ],
  "total": 123,
  "limit": 123,
  "offset": 123
}
Returns a paginated list of gateway configurations for the authenticated user’s organization.

​
Authentication

Requires organization admin authentication via Authorization: Bearer <token> header.

​
Query Parameters

​
limit
integer
default:"50"
Number of items per page (max 100)
​
offset
integer
default:"0"
Number of items to skip for pagination

​
Response

​
items
GatewayRead[]
Array of gateway objects
​
id
UUID
Gateway UUID
​
organization_id
UUID
Organization that owns this gateway
​
name
string
Human-readable gateway name
​
url
string
WebSocket URL of the gateway (e.g., ws://gateway-host:18789)
​
token
string
Authentication token for gateway RPC (may be omitted in responses)
​
workspace_root
string
Root directory for agent workspaces on the gateway host
​
gateway_agent_id
string
Stable gateway-main agent ID in the OpenClaw runtime (e.g., agent-01J...)
​
allow_insecure_tls
boolean
default:"false"
Whether to skip TLS certificate validation
​
disable_device_pairing
boolean
default:"false"
Whether device pairing is disabled (uses control_ui mode)
​
created_at
datetime
Creation timestamp
​
updated_at
datetime
Last update timestamp
​
total
integer
Total number of gateways
​
limit
integer
Items per page
​
offset
integer
Current offset

​
Example Request

curl -X GET "https://api.example.com/api/v1/gateways?limit=20" \
  -H "Authorization: Bearer your-token-here"

​
Example Response

{
  "items": [
    {
      "id": "55cc268a-4b45-400f-accf-201e025232ac",
      "organization_id": "org-123e4567-e89b-12d3-a456-426614174000",
      "name": "Production Gateway",
      "url": "ws://72.62.201.147:18789",
      "workspace_root": "/home/ubuntu/GDRIVE/Nuevo Agente/moltbot",
      "gateway_agent_id": "agent-01JCXYZ123",
      "allow_insecure_tls": false,
      "disable_device_pairing": true,
      "created_at": "2026-03-01T08:00:00Z",
      "updated_at": "2026-03-05T10:30:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

​
Gateway Configuration

​
Workspace Root

The workspace_root is the base directory on the gateway host where agent workspaces are created: 
{workspace_root}/
├── workspace-mc-{agent-uuid-1}/
│   ├── TOOLS.md
│   ├── IDENTITY.md
│   └── SOUL.md
└── workspace-mc-{agent-uuid-2}/
    ├── TOOLS.md
    └── ...

​
Device Pairing Mode

When disable_device_pairing=true, the gateway must have these settings in ~/.openclaw/openclaw.json: 
{
  "gateway": {
    "controlUi": {
      "allowInsecureAuth": true,
      "dangerouslyDisableDeviceAuth": true
    }
  }
}
Without these settings, RPC calls will fail with “missing scope: operator.read” errors.

​
Use Cases

  • Admin Dashboard: Display all configured gateways
  • Gateway Selection: Choose gateway for new agent provisioning
  • Health Monitoring: Check gateway connectivity and status
  • Configuration Review: Verify gateway settings before sync